<h4>Part of the "Frontier" website. San Francisco CA USA. {string.nthfield (clock.now (), ';', 1)}.<hr></h4>
<h2>Website Scripting for BBEdit 3.5</h2>
<blockquote>
***by Dave Winer, dwiner@well.com
<b>Important:</b> to view this file in a Netscape or Microsoft Internet Explorer, launch the UserLand Frontier application, bring BBEdit to the front and choose "Preview Page" from the Scripts menu.
***Introduction
Many people prefer to use BBEdit to write HTML text for their websites. With Frontier running in the background, BBEdit becomes more powerful, and building complex websites gets easier.
Here's what you get...
<ul>
<li>An extensible database of glossary terms, that you can refer to in "double-quotes" in your HTML text;
<li>A powerful macro language that runs while your pages are being built;
<li>Automatic enabling of URLs and mail addresses;
<li>Automatic substitution of special Macintosh characters for the equivalent HTML codes;
<li>An easy connection, via Fetch 3.0, to servers running on Unix and Windows NT and other operating systems;
<li>Support for web authors who can access their server disk thru Macintosh file sharing;
<li>Full source for all scripts are included, so all the features can be customized. The scripts have been designed to be modified and extended.
</ul>
***Requirements
This package requires BBEdit 3.5.2 or greater. It will not work with BBEdit Lite.
You'll need a compatible web browser to preview your pages, and Fetch 3.0 or greater to upload the resulting text to your server. Two browsers are compatible, Netscape 2.0 or greater and Microsoft Internet Explorer 2.0 or greater. In this text, anywhere it says "compatible browser" we mean either of these two applications.
***Frontier remains free
Frontier remains free and the new scripts are free. We want more people to use Frontier for website building. The goal is to grow the market, to make the Macintosh platform really excel at building powerful websites.
Both BBEdit and Frontier are important parts of the web content authoring platform for the Macintosh. This new release really bonds the products together, and opens the door for a closer connection in the future. BBEdit is an excellent commercial product from a company that upgrades its product and fixes bugs and cares for its customers. They deserve your support.
Many of these features were previously available in the Clay Basket website framework. Now they're available to all BBEdit users, whether or not they use Clay to manage their website.
***What to expect
After climbing a quick (and fun!) learning curve, you can move up to the kind of editorial power previously available only on customized Unix content development systems.
Very little knowledge of Frontier and no scripting is required for the Glossary and for automatic enabling of email addresses and URLs. You can use the macro feature without learning how to script by copying text from sample files, or by downloading macro libraries thru the scripting.com server.
You can go very far, as some people already have, because the macro facility opens up all the power and connections of the Frontier environment, its object database, and scriptable apps.
***Getting started
Open the Frontier folder. Launch the UserLand Frontier app. The Frontier app is "fat" -- it contains 68K code and Native PowerPC code. Naturally, it runs much faster on PowerMacs.
Launch BBEdit. You'll see a new menu at the end of BBEdit's menu bar, called Scripts. This menu contains calls scripts that run in Frontier.
***Page Preview
Create a new file in BBEdit, choose the New command from the File menu. Add a little text to the file, something like 'I just downloaded Frontier and it looks interesting.' Save the file to disk.
Launch Netscape or Microsoft Internet Explorer. Back in BBEdit, choose Page Preview from the Scripts menu. The browser comes to the front and displays the text in the frontmost BBEdit window. This is a key feature -- with a single keystroke you can see what your HTML text looks like in a browser. I use this command a lot when I'm tweaking up a page. Quick back and forth -- that's totally essential.
Now, another key feature. Back in BBEdit, type Frontier and put it in double-quotes, like this: \"Frontier". Choose Page Preview from the Scripts menu. In your browser, notice that it's a link. That's the glossary. It's mucho powerful! More info in the next section.
Note: This is not a replacement for BBEdit's "View HTML File" command, or for Lindsey Davies's extensions. The Page Preview script flows the text thru the macro processor, the BBEdit command displays the literal text, without expanding macros or glossary entries.
***The Glossary
When you get to a place in your web travels that you want to refer to in your website, add it to the Frontier glossary by choosing the Add to Glossary command in the web browser's Scripts menu, which appears when Frontier is running.
A dialog appears asking what you want to call the page. Enter a name and then click on OK. From that point on, when you put the name in double-quotes, a hotlink to that page will be generated.
Here are four examples: "CNN", "Suck", "Ignatius Reilly", "Netscape".
"Suck" remains in quotes because it is not in my glossary. When the macro processor encounters a glossary name that's not in the database, it leaves the text alone.
Note that when you view this text in a web browser, after the macro processor has run, the double-quotes are gone, each of them is replaced with a hotlink.
Glossary names are limited to 255 characters.
You can edit the contents of the glossary by chosing the Open Glossary command from BBEdit's Scripts menu. Frontier comes to the front and the glossary table is opened. Edit the text of this table as you would any text on a Macintosh. When you're finished making changes, press cmd-S to save to disk.
The glossary is an elegant approach to the problem that link validator software attempts to solve. By concentrating most or all of your links in the glossary, you can make a change in one place, rebuild all your pages, and all your links are cool. This gives you the power to correct URLs in one place.
***The future of glossaries
People on the "Frontier-Talk" list are working on glossary sharing tools that allow people to build networks of glossaries. The hooks are already in for much more powerful lookup facilities; more power can be added without changing any HTML code or any of the scripts.
A bit of philosophy about the glossary. After you use it for a bit, it becomes a basic resource for website stuff, like the Bookmarks menu in a web browser, with the difference that you have a collection of usable pointers for your web content, not just for your web browsing.
***Automatic treatment of special Mac characters
The web has a special way of indicating characters that aren't basic alphabetic and numeric characters, and the Macintosh does it a different way. When these characters are transmitted thru the web and viewed in a browser, they end up looking wrong to people who aren't using Macintoshes.
The solution was easy, we pass every character thru a special filter that converts Macintosh special characters to the equivalent sequence in HTML. So you can continue to use the Mac, and have all your web pages look right.
For example, if you type in Señorita into BBEdit, the HTML produced by the macro processor will say Señorita.
***Macros
Macros are simple, but they open the door for all kinds of automatic stuff. I use macros to generate tables of files you can download. In Clay Basket I use a macro to generate an outline of the website with hotlinks pointing to each of the pages. In this document I use a macro to help me document macros. Hmmmm.
A macro is a bit of text enclosed in \{curly braces}. When the text is processed, the text inside the braces is run thru Frontier's script interpreter. The text inside the curly braces is replaced with the value returned by the script. Therefore, macros can do anything a Frontier script can do.
Here's a simple example: <blockquote>\{(12 + 19) * 3} is replaced with {(12 + 19) * 3}.</blockquote>
Here are some other scripts and their values:<blockquote>
user.name = {user.name}
clock.now () = {clock.now ()}
Frontier.version () = {Frontier.version ()}
Frontier.shipDate = {Frontier.shipDate}
</blockquote>
Another thing macros can be used for -- to include standard "colors" -- to wear your badges that tell people about your politics, or what tools you use. For example, you can wear the BBEdit badge by including \{builtWithBBEdit ()} at the bottom your page. Here's what you'll get:
<center>{builtWithBBEdit ()}</center>
I did something like this for the 24 Hours of Democracy project. You can link to its home page with \{democracy24 ()}.
***Uploading with Fetch 3.0
I've added a command to the Scripts menu that uploads the current BBEdit file to a directory in my directory at www.hotwired.com.
If you want to use FTP to get your web files to the server, you can modify this script so it has the information for your server instead of mine.
The easiest way to edit the menu is to hold down the option key while selecting a command in the Scripts menu. Frontier comes to the front, opens an editing window for the Scripts menu and places the cursor on the command you selected.
Click on the Scripts button in the menu editor window. A new window opens containing the script. Change the values for domain and directory. Click on the Run button. A name and password dialog displays, then Fetch launches, and the frontmost file is uploaded to the server.
Close all the windows in Frontier, cmd-S to save changes, and try running the command from the Scripts menu. It should upload as it did before. Now, any time you want to upload a file to this directory you can do it with a single command.
***Uploading using the Mac file system
I've also included a command that copies the frontmost BBEdit window to a folder on a shared disk on my local network. Since I run a WebStar server on the same local net as my desktop machine, I can save the step of doing an FTP upload and can just use the Mac file system to copy the file to the server.
This script is even easier to modify. Open the script by choosing the Local Server command while holding down the option key. Click on the Script button. Change "Internal:Server Software:scripting.com:bbedit:" to a folder on your local net. Cmd-S to save, close all the windows in Frontier, bring BBEdit to the front. Now, whenever you want to save a file to your website just choose this command.
Note that both forms of uploading pass the text thru the macro processor before the upload happens.
***Automatic enabling of URLs and mail addresses
This part is really easy to explain!
When a URL or a mail address appears in the text of your page, the macro processor automatically turns it into a hotlink. Here are some examples:<ul>
<li>mom@home.com
<li>http://www.family.com/mom/
<li>http://www.isp.com/~junior/
<li>ftp://chat.sys.com/docs.sit.hqx
</ul>
You can override it by preceding the special character with a backslash. In email addresses, the key character is the at-sign. In URLs its the pair of slashes.
That's about all I can think of! It's a pretty simple feature.
***Looking at a real file
I've included the source text for this page in the Misc Stuff folder. It's called "Website Scripting". It's got lots of glossary references and macros.
***For Frontier experts
This section is for people who know how to use Frontier and how its object database works.
Your first question is likely to be Where do I store my macros? The answer is (of course!) anywhere you like. That doesn't help much.
There are two places we'll look first: user.html.macros and suites.html.data.standardMacros. All your macros run within a "with" statement that includes both of those tables.
In general, you should never put a macro in the standardMacros table because new releases of suites.html will clobber these scripts. I won't add many scripts to this table, only ones that I believe every author should have.
If you have a macro that you think you'll use in every website, store it in the user.html.macros table. Or store it there if you don't want to think too much.
If you have a website built with a complex set of scripts that interact with each other, start a new suite. This makes it easier to work on, and makes it possible for you to share your set of macros with other script writers.
***General Notes
If a macro generates an error, the error message is inserted into the HTML text inside bold square brackets.
Any time the macro processor sees two consecutive carriage returns a <p> tag is inserted.
Any time you want to override the effect of a special character, precede it with a backslash. So if you don't want an email address to be hot, put a backslash before the at-sign.
To maintain backward compatibility with Clay Basket two special markups are supported. Any line that begins with three asterisks is boldfaced. Any line that contains only three dashes becomes a separator line. It's often easier to use the <b> and <hr> tags.
When you quit Frontier it will ask if you want to save changes. You should always choose to save changes. Is this a design flaw? Maybe.
Many of the scripts in this package will work with other HTML editors, such as PageMill or SiteMill, but I chose to do it for BBEdit first because so many professional web developers use it, and also because it is scriptable and supports menu sharing.
I like to use Fetch to do my uploads because it works with all the FTP servers I have to work with. I don't have anything against Anarchie, or Peter N. Lewis, I just use Fetch because it works for me. I'm sure Peter will understand.
All the text handled by Frontier's macro processor flows thru a template. You can edit the template. First, bring Frontier to the front. Press cmd-J. Enter user.html.templates.bbedit. It says <meat>. You can put stuff before that tag and after that tag. That stuff will appear on all pages rendered by Frontier.
***Pointers
Here's a list of places containing more useful information: <ol>
<li>"Bare Bones Software", makers of BBEdit.
<li><a href="http://www.scripting.com/frontier/">Frontier</a> Community Center website.
<li><a href="http://www.scripting.com/frontier/siegel.html">Email</a> from Rich Siegel to Guy Kawasaki.
</ol>
</blockquote>
<hr><center><table border=0>
<td valign=top>"cactus"</td>
<td valign=top><h4>This page was last built with "BBEdit" and "Frontier" on a "Macintosh" on {string.dateString ()} at {string.timeString ()}. Thanks for checking it out! "Dave"</h4></td>
